<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>OpenTBS - create OpenOffice and Ms Office documents with PHP</title>
<style type="text/css">
<!--
body, td, th {
	font-family: Arial, sans-serif;
	font-size: 13px;
}
h4 {
	font-size: 13px;
	font-weight:normal;
	margin-bottom: 5px;
}
h5 {
	font-size: 13px;
	font-weight:normal;
	text-decoration:underline;
	margin-bottom: 5px;
}
ul {
	list-style-type:square;
	list-style-position:inside;
	padding-left:0;
}
.shift {
	margin-left: 10px;
	padding: 3px;
}
.code {
	font-family: "Courier New", Courier, monospace;
	font-size: 13px;
	color: #036;
	background-color: #E1EBFF;
	padding-top: 3px;
	padding-bottom: 3px;
}
.template {
	font-family: "Courier New", Courier, monospace;
	font-size: 12px;
	color: #030;
	background-color: #E1FFEB;
	padding-top: 3px;
	padding-bottom: 3px;
}
.versioning {
	font-style: italic;
	color: #060;
}
.smallcode {
	font-family: "Courier New", Courier, monospace;
	font-size: 13px;
	color: #036;
}
.warning {
	color: #F30;
}
-->
</style>
<meta name="Keywords" content="openxml, odf, template" />
</head>

<body>
<h1>OpenTBS - create OpenOffice and Ms Office documents with PHP</h1>
<div>version 1.7.6, 2012-06-06, by Skrol29<br />
  help file modified on 2012-06-06</div>
<ol>
  <li><a href="#intro">Introduction</a></li>
  <li><a href="#install">Installing</a></li>
  <li><a href="#principles">Understanding principles</a></li>
  <li><a href="#coding">Synopsis and code examples</a>
    <ul>
      <li>4.1. <a href="#preparation">Preparation of TinyButStrong Template Engine with the OpenTBS plug-in</a></li>
      <li>4.2. <a href="#loadtemplate">Method LoadTemplate()</a></li>
      <li>4.3. <a href="#show">Method Show()</a></li>
      <li>4.4. <a href="#chart">Change data of series in charts</a></li>
      <li>4.5. <a href="#pic">Change pictures in the document</a></li>
      <li>4.6. <a href="#modify_contents">Manual modification in the contents</a></li>
      <li>4.7. <a href="#modify_files">Manual modification of files in the archive</a></li>
      <li>4.8. <a href="#misc">Miscellaneous</a></li>
    </ul>
  </li>
  <li><a href="#demo">Demo</a></li>
  <li><a href="#debug">Debugging your template</a></li>
  <li><a href="#zlib">What to do if Zlib extension is not enabled with PHP?</a></li>
  <li><a href="#changelog">Changelog</a></li>
  <li><a href="#license">License</a></li>
</ol>
<h2><a name="intro" id="intro"></a>1. Introduction</h2>
<p>OpenTBS is a plug-in for the <a href="http://www.tinybutstrong.com">TinyButStrong</a> Template Engine. <br />
  <br />
  TinyButStrong is a  PHP Template Engine which has  special template syntax and allows you to design templates in their natural editing tools. But it normally works only for  Text files, including XML and HTML. <br />
  <br />
  With TinyButStrong and its plug-in OpenTBS, you can use the template engine to  merge <strong>OpenOffice</strong> documents and <strong>Ms Office </strong> documents with lot of facilities.   All <strong>OpenDocument Format</strong> (ODF) and <strong> Office Open XML</strong> (OOXML) can be merged with OpenTBS, and also XPS files (XPS is a PDF competitor provided by Microsoft). In fact, all zip archives containing Xml/Html/Text files can be merged with OpenTBS.</p>
<h5>What is special to OpenTBS:</h5>
<ul>
  <li>Design your templates directly with OpenOffice or MS Office.</li>
  <li>No exe file needed to merge documents.</li>
  <li>No temporary files needed to merge documents.</li>
  <li>Output directly as an http download, a new file on the disk, or as a string (for file attachment  for example).</li>
  <li>Works with both PHP 4 and PHP 5.</li>
  <li>No PHP extension is required (If the Zlib extension is enabled it becomes  easier to use  templates, see more detail below)</li>
</ul>
<p> You should know Template Engines and more specifically <a href="http://www.tinybutstrong.com">TinyButStrong</a> to use 
  OpenTBS.</p>
<h2><a name="install" id="install"></a>2. Installing</h2>
<h5>Requirements:</h5>
<ul>
  <li>TinyButStrong version 3.7.0 or higher. (OpenTBS versions &lt;= 1.5.0 require TinyButStrong version 3.6.0 or higher)</li>
  <li>PHP 4.3 or higher, PHP 5</li>
  <li>It is better to have the <a href="http://www.php.net/manual/en/book.zlib.php">Zlib</a> extension enabled on your PHP installation. If it's not, <a href="#zlib">here is what to do</a>.</li>
</ul>
<h5>Installation:</h5>
<p> Just put the file &quot;tbs_plugin_opentbs.php&quot; with your PHP scripts.</p>
<h2><a name="principles" id="principles"></a>3. Understanding principles</h2>
<p>It is important to figure out that OpenOffice and Ms Office (since version 2007) documents are technically zip archives containing XML files, even if the extension of the document is not &quot;.zip&quot;. Those zip archives can contain other file types like pictures or sounds, but the document structure and the text contents are saved as  XML files. The <a href="xml_synopsis.txt">XML Synopsis</a> summarizes the key entities of XML sub-files contained in OpenOffice and Ms Office documents.</p>
<p>TinyButStrong can merge XML files, but cannot read zip archives by itself. The plug-in OpenTBS extends the TinyButStrong methods <a href="http://www.tinybutstrong.com/manual.php#php_loadtemplate">LoadTemplate()</a> and <a href="http://www.tinybutstrong.com/manual.php#php_show">Show()</a> to make them working with zip archives. <span id="result_box"><span title="">But you   do not have to bother with it because OpenTBS is managing archives  in a way that is invisible for you.</span></span></p>
<p> When the OpenTBS plugin is installed, the LoadTemplate() method becomes able to first load a zip archive (an OpenOffice or Ms Office document), and then to load the contents of any XML or Text files stored in the archive. You can then merge the contents of XML or Text files with all features of the TinyButStrong template engine. At the end, the Show() method does render the entire zip archive including  modified stored files. The render can be done as an HTTP download, a news file on the server's disk, or in a PHP string.</p>
<p>Since OpenTBS version 1.3, you can also add and delete files in the archive. Before this version you could only modify existing files in the archive.<br />
</p>
<p> <a name="extension" id="extension"></a>OpenTBS has <strong>automatic extension recognition</strong>. When you load a document which has one of the following extensions { odt, odg, ods, odf, odp, odm, docx, xlsx, pptx }, then the main XML file of the archive are automatically  loaded, and some special character conversion are preset. For example, for all OpenDocument  files, the stored file  &quot;content.xml&quot; is automatically loaded.<br />
  Since  version 1.6.0, 
  if the extension is not recognized then OpenTBS also try to find the document by the sub-file presence. And if all fails, then you can force the document type using a <a href="#force_doctype">special command</a>.</p>
<h2><a name="coding" id="coding"></a>4. Synopsis and code examples</h2>
<h3><a name="preparation" id="preparation"></a>4.1. Preparation of TinyButStrong Template Engine with the OpenTBS plug-in</h3>
<div class="shift code">include_once('tbs_class.php');<br />
  include_once('tbs_plugin_opentbs.php');<br />
  <br />
  $TBS = new clsTinyButStrong;<br />
  $TBS-&gt;Plugin(TBS_INSTALL, OPENTBS_PLUGIN);</div>
<h3><a name="loadtemplate" id="loadtemplate"></a>4.2. Method LoadTemplate()</h3>
<h4>&bull; Load an archive with the automatic extension recognition (<a href="#extension">explained above</a>): </h4>
<div class="shift">
  <div class="code">$TBS-&gt;LoadTemplate('document.odt'); // Load the archive 'document.odt'.</div>
</div>
<h4>&bull; Load an archive without the automatic extension recognition:</h4>
<div class="shift"><span class="versioning">(supported since OpenTBS version 1.1)</span>
  <div class="code">$TBS-&gt;LoadTemplate('document.odt#');</div>
</div>
<h4>&bull; Load an archive and one file stored in this archive:</h4>
<div class="shift code">$TBS-&gt;LoadTemplate('document.odt#content.xml');</div>
<h4>&bull; Load an archive and several files stored in this archive:</h4>
<div class="shift code">$TBS-&gt;LoadTemplate('document.odt#content.xml;settings.xml');</div>
<h4>&bull; Load a stored file from the current archive:</h4>
<div class="shift">
  <div class="code">$TBS-&gt;LoadTemplate('#content.xml'); // Load the stored file 'content.xml' from the current archive.</div>
  <p>The archive must be previously loaded.<br />
    If the file is stored in a subfolder, then indicate the full path. For example: 'word/document.xml'.</p>
</div>
<h4>&bull; Load an archive with special data conversion:</h4>
<div class="shift"><span class="versioning">(supported since OpenTBS version 1.3.2)</span>
  <div class="code">$TBS-&gt;LoadTemplate('document.odt', OPENTBS_ALREADY_UTF8);</div>
  <p>OpenTBS manages XML files that are UTF8 encoded. But by default, it assumes that all the data to merge (which can come from PHP or SQL) is Ascii encoded, and thus it performs conversions. If you want to define the data conversion, then you can use one of the following constants:</p>
  <ul>
    <li><span class="smallcode">OPENTBS_DEFAULT</span>: OpenTBS assumes that all data is ASCII encoded,</li>
    <li><span class="smallcode">OPENTBS_ALREADY_UTF8</span>: OpenTBS assumes that all data is already UTF8 encoded,</li>
    <li><span class="smallcode">OPENTBS_ALREADY_XML</span>: OpenTBS assumes that all data is already XML encoded, and thus it won't convert data at all. Take care of that option.</li>
  </ul>
  <p> Please note that if 
    you need to change the data conversion for one or few fields only in your template, then you can use parameter &quot;<span class="smallcode">htmlconv</span>&quot; (see the TBS documentation for more details). </p>
</div>
<h3><a name="show" id="show"></a>4.3. Method Show()</h3>
<p>Render options for OpenTBS:</p>
<h4>&bull; Render the merged archive as an HTTP download: ($file_name is optional)</h4>
<div class="shift code">$TBS-&gt;Show(OPENTBS_DOWNLOAD, $file_name);</div>
<h4>&bull; Render the merged archive as an HTTP output with your customized HTTP headers:</h4>
<div class="shift code">header(...); // your custom headers here<br />
  $TBS-&gt;Show(OPENTBS_NOHEADER); // output the binary file without header</div>
<h4>&bull; Render the merged archive as a new file saved on the server's disk:</h4>
<div class="shift code">$TBS-&gt;Show(OPENTBS_FILE, $file_name);</div>
<h4>&bull; Render the merged archive as a PHP string:</h4>
<div class="shift"> <span class="versioning">(supported since OpenTBS version 1.1)</span>
  <div class="code"> $TBS-&gt;Show(OPENTBS_STRING);<br />
    $string = $TBS-&gt;Source; </div>
  <p>When you use <span class="smallcode">OPENTBS_STRING</span> then there is no output for the client. But instead, the binary source of the archive is placed into property $TBS-&gt;Source. This feature can be useful, for example, when you want to place the merged document into an email as an attached file.</p>
</div>
<h3><a name="chart" id="chart"></a>4.4. Change data of series in charts</h3>
<h4>&bull; Change series in charts:</h4>
<div class="shift"> <span class="versioning">(supported since OpenTBS version 1.6.0, for Ms Word only)</span>
  <div class="code">Example: $TBS-&gt;PlugIn(OPENTBS_CHART, $ChartNameOrNum, $SeriesNameOrNum, $NewValues, $NewLegend=false)</div>
  <p>This command changes the values of a series in a Chart of the document. The chart will be automatically actualized when the merged document is opened because OpenTBS also breaks the link between the chart and its cached view.<br />
    The result is <span class="smallcode">true</span> if the series is modified with success, otherwise the result is <span class="smallcode">false</span>. <br />
  </p>
  <table width="100%" border="0" cellspacing="2" cellpadding="0">
    <tr>
      <th align="left" valign="top">Argument</th>
      <th align="left">Description</th>
    </tr>
    <tr>
      <td valign="top" class="smallcode">$CharteNameOrNum</td>
      <td>Internal name of the XML file that contains the chart definition (with or without the extension), or the  order number of the chart in the document (first is number 1).<br />
        You can use the command <a href="#debugmode">OPENTBS_DEBUG_CHART_LIST</a> in order to view all chart internal names in the document.<br />
        <span class="smallcode">$CarteNameOrNum</span> is typically <span class="smallcode">'chart1'</span> or <span class="smallcode">1</span>.</td>
    </tr>
    <tr>
      <td valign="top" class="smallcode">$SeriesNumOrName</td>
      <td>Exact caption of the series in the chart, or its number (first is number 1). Typically <span class="smallcode">'Series 1'</span> or <span class="smallcode">1</span>. </td>
    </tr>
    <tr>
      <td valign="top" class="smallcode">$NewValues</td>
      <td>The new data of the series. Must be an array, or value <span class="smallcode">false</span> if you want to delete the series.<br />
        The array can store data with 2 possibilities:<br />
        <span class="code">$NewValues = array( array('cat1', 'cat2', 'cat3', ...), array(val1, val2, val3, ...) );</span><br />
        or <br />
        <span class="code">$NewValues = array('cat1'=&gt;val1,  'cat2'=&gt;val2, 'cat3'=&gt;val3, ...);</span><br />
        If the chart type is &quot;X Y (Scatter)&quot; then you must use only the  first data store type.</td>
    </tr>
    <tr>
      <td valign="top" class="smallcode">$NewLegend</td>
      <td>Optional. The new caption of the series. </td>
    </tr>
  </table>
  <h5>Please note:</h5>
  <ul>
    <li>The type of the chart won't be changed.</li>
    <li>Some charts may not be recognized by this feature when the Word document is created with Word &lt;= 2007 or is saved with a Compatibility Mode. You have to convert charts to have it work (right on the chart and choose &quot;Convert&quot;). You can use the command <a href="#debugmode">OPENTBS_DEBUG_CHART_LIST</a> in order to view all unsupported   charts in the document.</li>
  </ul>
</div>
<h3><a name="pic" id="pic2"></a>4.5. Change pictures in the document</h3>
<h4>&bull; Change an internal picture with a new one:</h4>
<div class="shift"> <span class="versioning">(supported since OpenTBS version 1.4.0, for OpenOffice and MsOffice documents only)</span>
  <div class="template">Example: [onshow.x;ope=changepic;from='../pic/[val].gif';as='[val].gif';default=current]</div>
  <p>I the example above, $x is a PHP global variable containing the name or the path for an external picture file. But the feature  works simillary with items data merged with a TBS block.</p>
  <p> When a TBS field having <span class="smallcode">&quot;ope=changepic&quot;</span> is merged in the template, then OpenTBS will search the first picture located before the field (to be more precise, the TBS field must be located somewhere inside or after the opening tag of the picture in the template source code), and then it will change the picture assuming that the value of the field is the path for a picture file on the server. You don't have to care about loading the picture file in the document, OpenTBS will manage this for you.</p>
  <p>Note that parameter <span class="smallcode">&quot;ope=changepic&quot;</span> is  a feature provided by the OpenTBS plug-in, which extends the &quot;<a href="http://www.tinybutstrong.com/manual.php#html_field_prm_ope">ope</a>&quot; parameter natively present with TBS.<br />
    <br />
    In order to 
    simplify your coding, they are other complementary parameters that are provided for the <span class="smallcode">changepic</span> parameter: </p>
  <table border="0" cellpadding="0" cellspacing="4" style="marging-left:20px;">
    <tr>
      <th align="left">Parameter</th>
      <th align="left">Description</th>
    </tr>
    <tr>
      <td valign="top"><span class="smallcode">from</span></td>
      <td>Reformulate the path of the picture to insert. The parameter's value can contain the [val] keyword or any [var] fields, they work the same way as with parameter &quot;<a href="http://www.tinybutstrong.com/manual.php#html_field_prm_file">file</a>&quot;. Parameter &quot;<span class="smallcode">from</span>&quot; is optional.</td>
    </tr>
    <tr>
      <td valign="top"><span class="smallcode">as</span></td>
      <td> Reformulate name of the picture that it will take inside the document. It is rare to need it, but it can help in some cases. Note that the external picture file is not renamed. The new   name must be defined without path.
        The parameter's value can contain the [val] keyword or any [var] fields, they work the same way as with parameter &quot;<a href="http://www.tinybutstrong.com/manual.php#html_field_prm_file">file</a>&quot;. Parameter <span class="smallcode">&quot;as&quot;</span> is optional.</td>
    </tr>
    <tr>
      <td valign="top"><span class="smallcode">default</span></td>
      <td>Define the picture that should be used when the expected one is not found. The parameter's value must be the path of a file on the server, or the keyword &quot;<span class="smallcode">current&quot;</span>. If you've set <span class="smallcode">&quot;default=current&quot;</span> then OpenTBS will let the picture of the template if the expected one is not found.</td>
    </tr>
    <tr>
      <td valign="top"><span class="smallcode">adjust</span></td>
      <td>Adjust the size of the picture in the document. This parameter requires that PHP is configured with the <a href="http://www.php.net/manual/en/book.image.php">GD</a> extension, which is usually the case.<br />
        Values can be on of the followings:<br />
        <table border="0" cellspacing="0" cellpadding="3">
          <tr>
            <td valign="top"><span class="smallcode">adjust</span> (or <span class="smallcode">adjust=inside</span>)</td>
            <td>The picture is adjusted to enter into the picture bounds of the template.</td>
          </tr>
          <tr>
            <td valign="top"><span class="smallcode">adjust=samewidth</span><br /></td>
            <td>The picture is adjusted to have the same width than the picture of the template.</td>
          </tr>
          <tr>
            <td valign="top" class="smallcode">adjust=sameheigth</td>
            <td>The picture is adjusted to have the same height than the picture of the template.</td>
          </tr>
          <tr>
            <td valign="top"><span class="smallcode">adjust=100%</span> (or 
              another pourcentage) </td>
            <td>The picture is adjusted to be  proportional to the originial size.</td>
          </tr>
        </table>
        <span class="versioning">Parameter adjust is supported since OpenTBS version 1.7.0.</span></td>
    </tr>
  </table>
</div>
<h3><a name="modify_contents" id="modify2"></a>4.6. Manual modification in the contents</h3>
<p><span class="versioning">The following commands are supported since OpenTBS version 1.7.0</span>:</p>
<table border="0" cellspacing="1" cellpadding="0">
  <tr>
    <th align="left">Command</th>
    <th align="left">Desciption</th>
  </tr>
  <tr>
    <td valign="top" nowrap="nowrap"><span class="smallcode">$TBS-&gt;PlugIn(OPENTBS_SELECT_MAIN)</span></td>
    <td>Select and load the main sub-file in the opened template. For example in a Writer document, or an Ms Word document, this command can bring you back from the merging of a header to the main body.</td>
  </tr>
  <tr>
    <td valign="top" nowrap="nowrap" class="smallcode">$TBS-&gt;PlugIn(OPENTBS_SELECT_SHEET, $Sheet)</td>
    <td><p>Select and load the sub-file corresponding to $Sheet.<br />
      This command will raise an error if the opened template is not a Workbook (Ms Word or OpenOffice Calc).      This command is useless for an 
    OpenOffice Calc workbook because all sheets are saved in single sub-file. Nevertheless using it  won't raise an error.<br />
     <span class="smallcode">$Sheet</span> must be a sheet identifier.<br />
     A sheet identifier can be 
     either an integer corresponding to the index of the sheet, or a string corresponding to the name of the sheet.<br />
    Use command <span class="smallcode">$TBS-&gt;PlugIn(<a href="#debugmode">OPENTBS_DEBUG_INFO</a>)</span> to list all id and name of sheets in current Workbook.</p></td>
  </tr>
  <tr>
    <td valign="top" nowrap="nowrap" class="smallcode">$TBS-&gt;PlugIn(OPENTBS_DISPLAY_SHEETS, $Sheets[, $Visible])</td>
    <td>Make one or several sheets visible or hidden.<br />
      This command will raise an error if the opened template is not a Workbook.<br />
      <span class="smallcode">$Sheets</span> must be an array of sheet identifier, or even a single sheet identifier. See command <span class="smallcode">OPENTBS_SELECT_SHEET</span> for more details about sheet identifiers.<br />
      <span class="smallcode">$Visible</span> must be a boolean, default value is <span class="smallcode">true</span>.</td>
  </tr>
  <tr>
    <td valign="top" nowrap="nowrap" class="smallcode">$TBS-&gt;PlugIn(OPENTBS_DELETE_SHEETS, $Sheets[, $Delete])</td>
    <td>Make on or several sheets deleted or not.<br />
This command will raise an error if the opened template is not a Workbook.<br />
<span class="smallcode">$Sheets</span> must be an array of sheet identifier, or even a single sheet identifier. See command <span class="smallcode">OPENTBS_SELECT_SHEET</span> for more details about sheet identifiers.<br />
<span class="smallcode">$Delete</span> must be a boolean, default value is <span class="smallcode">true</span>.<br />
<em class="warning">Please note that for now, you must not delete a sheet that contains a Pivot Table because  this will produce an error when the workbook is opened.</em></td>
  </tr>
  <tr>
    <td valign="top" nowrap="nowrap" class="smallcode">$TBS-&gt;PlugIn(OPENTBS_DELETE_COMMENTS)</td>
    <td>Delete all usual user comments in the opened template. </td>
  </tr>
  <tr>
    <td valign="top" nowrap="nowrap"><span class="smallcode">$TBS-&gt;PlugIn(OPENTBS_DELETE_ELEMENTS, $Elements)</span></td>
    <td>Delete XML elements in the current sub-file.<br />
      <span class="smallcode">$Elements</span> must be an array of strings. For example:<br />
      <span class="smallcode">$Elements = array('w:bookmarkStart', 'w:bookmarkEnd')</span><br /> 
      This will delete all bookmarks in an Ms Word document.
</td>
  </tr>
</table>
<h3><a name="modify_files" id="modify_files"></a>4.7. Manual modification of files in the archive</h3>
<h4 style="display:inline">&bull; Check if a file does exists in the archive:</h4>
<div class="shift">
  <div class="code">$TBS-&gt;Plugin(OPENTBS_FILEEXISTS, $Name)
</div>
  <p>Return <span class="smallcode">true</span> or <span class="smallcode">false</span>. $Name must include the inner path.<br />
  For example : $Name = 'META-INF/manifest.xml';</p>
  <div class="versioning">(supported since OpenTBS version 1.7.4)</div>
</div>
<h4>&bull; Add any new file in the archive:</h4>
<div class="shift">
  <div class="code">// OpenTBS &gt;= 1.6.0<br />
    $TBS-&gt;Plugin(OPENTBS_ADDFILE, $Name, $Data, $DataType=OPENTBS_STRING, $Compress=true); <br />
    <br />
    // Deprecated since OpenTBS 1.6.0<br />
    $TBS-&gt;Plugin(OPENTBS_PLUGIN, OPENTBS_ADDFILE, $Name, $Data, $DataType=OPENTBS_STRING, $Compress=true);  </div>
  <p> If $Data is false then the previously add file with the given name is canceled if any.</p>
<p> $DataType must be  <span class="smallcode">OPENTBS_STRING</span> if $Data is  the content to add ; it must be <span class="smallcode">OPENTBS_FILE</span> if $Data is the path of the external file to insert.</p>
  <p> $Compress can be true, false or an array with keys ('meth','len_u','crc32') which means that the data is already previously compressed.</p>
  <div class="versioning">(supported since OpenTBS version 1.3)</div>
</div>
<h4>&bull; Replace an existing file in the archive:</h4>
<div class="shift"> 
  <div class="code">$TBS-&gt;Plugin(OPENTBS_DELETEFILE, $Name, $Data, $DataType=OPENTBS_STRING, $Compress=true);
  </div>
  <p>The arguments are the same as command <span class="smallcode">OPENTBS_ADDFILE</span>.<br />
    Please note that any TBS 
  merge on a file in the archive will cancel previous or future replacements.</p>
  <div class="versioning">(supported since OpenTBS version 1.7.4)</div>
</div>
<h4>&bull; Delete an existing file in the archive:</h4>
<div class="shift"> 
  <div class="code">// OpenTBS &gt;= 1.6.0<br />
    $TBS-&gt;Plugin(OPENTBS_DELETEFILE, $Name);<br />
    <br />
// Deprecated since OpenTBS 1.6.0<br />
    $TBS-&gt;Plugin(OPENTBS_PLUGIN, OPENTBS_DELETEFILE, $Name);</div>
  <p>Delete the existing file in the archive, or a file previously   added using the <span class="smallcode">OPENTBS_ADDFILE</span> command.</p>
  <div class="versioning">(supported since OpenTBS version 1.3)</div>
</div>
<h4>&bull; Reset all modifications in the  archive:</h4>
<div class="shift"> 
  <div class="code">// OpenTBS &gt;= 1.6.0<br />
    $TBS-&gt;Plugin(OPENTBS_RESET);<br />
    <br />
// Deprecated since OpenTBS 1.6.0<br />
    $TBS-&gt;Plugin(OPENTBS_PLUGIN, OPENTBS_RESET);</div>
  <p>The automatic extension recognition is also applied as it was applied for the first load of the archive.</p>
</div>
<h3><a name="misc" id="misc"></a>4.8. Miscellaneous</h3>
<h4>&bull; Dealing with apostrophes:</h4>
<div class="shift">
  <p> Both OpenOffice and Ms Office may automatically convert single quotes (') into typographic apostrophes (&rsquo;), depending to the auto-correction options. This may be annoying   when you need to code a TBS fields that have a single quote. That's why OpenTBS automatically convert by default all (&rsquo;) back to single quotes (') in documents.<br />
    If you want to stop this conversion, you can set <span class="smallcode">$TBS-&gt;OtbsConvertApostrophes = false;</span> and no apostrophes   will be converted. Note that you can avoid the auto-correction of single quotes (') in Ms Word using keys[ctrl]+[z], and in OpenOffice using the cancel button.<br />
   </p> <div class="versioning">Property OtbsConvertApostrophes is supported since OpenTBS version 1.6.0.</div>
</div>
<h4><a name="force_doctype" id="demo4"></a>&bull; Forcing the document type recognition:</h4>
<div class="shift">
  <p>You can force the document type recognition using command OPENTBS_FORCE_DOCTYPE. Example:</p>
  <div class="code"> $TBS-&gt;PlugIn(OPENTBS_FORCE_DOCTYPE, 'docx');</div>
  <p class="versioning">This command is supported since OpenTBS version 1.6.0.</p> </div>
<h4>&bull; Retrieving the name of the current document:</h4>
<div class="shift">
  <p> Property <span class="smallcode">$TBS-&gt;tbsCurrFile</span> indicates the name of the current file loaded from the archive. The value is false if no file is loaded yet from the archive.</p>
  <p> Other TinyButStrong methods and properties stay unchanged and are available for merging your template. </p>
  <div class="versioning">(supported since OpenTBS version 1.1)</div>
</div>
<h2><a name="demo" id="demo"></a>5. Demo</h2>
<p>The OpenTBS package includes a full set of runnable templates. Some templates can contain useful complementary information for designing.<br />
  Run the following demo under PHP: <a href="http://www.tinybutstrong.com/plugins/opentbs/demo">OpenTBS demo</a></p>
<h2><a name="debug" id="debug"></a>6. Debugging your template</h2>
<p><a name="debugmode" id="debugmode2"></a>Since OpenTBS version 1.6.0, there are several commands for debugging. Please note that those commands do not exit the process.</p>
<table border="0" cellspacing="1" cellpadding="0">
  <tr>
    <th align="left">Command</th>
    <th align="left">Desciption</th>
  </tr>
  <tr>
    <td valign="top" nowrap="nowrap" class="smallcode">$TBS-&gt;PlugIn(OPENTBS_DEBUG_INFO [, $Exit])</td>
    <td>Display technical information about the current loaded template, including sheet information if the template is a workbook, and chart information if the template have some.<br />
      <span class="smallcode">$Exit</span> must be a boolean, default value is <span class="smallcode">true</span>.</td>
  </tr>
  <tr>
    <td valign="top" nowrap="nowrap" class="smallcode">$TBS-&gt;PlugIn(OPENTBS_DEBUG_XML_CURRENT)</td>
    <td>Display XML contents of sub-files already opened and modified for merging. XML is indented in order to improve reading.</td>
  </tr>
  <tr>
    <td valign="top" nowrap="nowrap" class="smallcode">$TBS-&gt;PlugIn(OPENTBS_DEBUG_XML_SHOW)</td>
    <td>Ends the merge process as if the final document was created. But instead of creating the document, displays  
  the XML contents of sub-files  modified for merging. XML is indented in order to improve reading.</td>
  </tr>
</table>
<p>There is  also deprecated debug options:</p>
<table border="0" cellspacing="1" cellpadding="0">
  <tr>
    <th align="left">Command</th>
    <th align="left">Desciption</th>
  </tr>
  <tr>
    <td valign="top" nowrap="nowrap" class="smallcode">$TBS-&gt;PlugIn(OPENTBS_DEBUG_XML)</td>
    <td>Does the same as <span class="smallcode">$TBS-&gt;PlugIn(OPENTBS_DEBUG_XML_SHOW);</span><br />
    <span class="versioning">Supported since OpenTBS version 1.3.2.</span></td>
  </tr>
  <tr>
    <td valign="top" nowrap="nowrap" class="smallcode">$TBS-&gt;PlugIn(OPENTBS_DEBUG_XML+OPENTBS_DEBUG_AVOIDAUTOFIELDS)</td>
    <td>Avoid merging of [onload], [onshow] and [var].<span class="versioning">Supported since OpenTBS version 1.3.2.</span></td>
  </tr>
  <tr>
    <td valign="top" nowrap="nowrap" class="smallcode">$TBS-&gt;Render = OPENTBS_DEBUG_AVOIDAUTOFIELDS;</td>
    <td> Work also in property Render.<span class="versioning">Supported since OpenTBS version 1.3.2.</span><br /></td>
  </tr>
  <tr>
    <td valign="top" nowrap="nowrap" class="smallcode">$TBS-&gt;PlugIn(OPENTBS_DEBUG_CHART_LIST)</td>
    <td>Does the same as <span class="smallcode">$TBS-&gt;PlugIn(OPENTBS_DEBUG_INFO);</span><span class="versioning">Supported since OpenTBS version 1.6.0.</span></td>
  </tr>
</table>
<p>Otherwise, here are some indications that may help for the issues you can met with merging:</p>
<h3>a) The merged document is producing error messages when opened with its application (OpenOffice or Ms Office)</h3>
<p>The most likely causes are:</p>
<p>&bull; You've chosen the <span class="smallcode">OPENTBS_DOWNLOAD</span> render option but a php error message or any other unexpected content has been output before by PHP.</p>
<p class="shift">Activate the <a href="#debugmode">debug mode</a> using the command <span class="smallcode">OPENTBS_DEBUG_XML_SHOW</span>, it helps to check PHP error message and other unexpected content.</p>
<p>&bull; The merging has produced an invalid document or an invalid XML content in an XML file  of the document.</p>
<p class="shift">Activate the <a href="#debugmode">debug mode</a> using  it helps to check the XML contents of merged files.</p>
<p> See section (b) below for more information in the XML structure of the files.</p>
<h3>b) The merged document is well opened by its application (OpenOffice or Ms Office) but the content is not designed as expected</h3>
<p>First, you can have a look the <a href="#demo">demo templates</a>, they contain examples and advices for each type of document.<br />
  And to go further: even if you can edit your template using directly OpenOffice or Ms Office, you will probably need to understand the XML tags and attributes to complete your merge. The file <a href="xml_synopsis.txt">xml_synopsis.txt</a> is a small synopsis of the XML structure you can found in the inner source of those documents. Have a look to it if you feel lost.</p>
<h3>c) Go deeper in the debugging</h3>
<p>You can view the inner source of a document using a zip software like <a href="http://www.7-zip.org/">7-Zip</a>. It allows you to open an archive even if the extension is not &quot;.zip&quot;.<br />
</p>
<ul>
  <li>Open the merged document with 7-Zip (or your other zip software),</li>
  <li> extract the main XML file (or another file that you've merged),</li>
  <li> then open the XML file in an Text Editor software.</li>
  <li>those XML files are usually saved with no line breaks, which make them hard to be read. Some Text Editors can reformat them. You can also use the <a href="#debugmode">debug mode</a> to see the formatted XML.</li>
  <li>check the structure of the XMK, try some fix and arrangements, deleted suspicious parts, ...</li>
  <li>put the modified XML file back to the archive, and test if it's correctly opened with its application (OpenOffice, Ms Office)</li>
</ul>
<h2><a name="zlib" id="zlib"></a>7. What to do if Zlib extension is not enabled with PHP?</h2>
<p>OpenTBS uses  Zlib functions in order to automatically uncompress and recompress files stored in the zip archive. If Zlib is not enabled, then you have to use your own uncompress/compress tool, or to prepare the template to have files uncompressed in the zip archive.</p>
<p><u>Example to uncompress the &quot;content.xml&quot; file in an ODT document using 7-Zip:</u><br />
  1) open the ODT file with 7-Zip<br />
  2) extract the &quot;content.xml&quot; file from the ODT file in the same folder than the ODT file<br />
  3) 
  close 7-Zip<br />
  4) 
  open 7-Zip, and change current directory to be the same as the ODT file<br />
  5) select the 
  &quot;content.xml&quot; file and click on button [Add], or menu [File][7-Zip][Add to archive...]<br />
  6) A new  window named &quot;Add to archive&quot; is opened,<br />
  &nbsp;&nbsp;&nbsp;&nbsp;- replace the archive name with the ODT file name,<br />
  &nbsp;&nbsp;&nbsp;&nbsp;- set the Compression level to &quot;None&quot;.<br />
  7) Click on [Ok]<br />
  If you re-open the ODT file with 7-Zip, you can notice that the size and the uncompressed size are the same.<br />
  If the file should be placed in a sub-folder of the archive, then open the archive and rename the file in order to move it in a folder. For example rename &quot;manifest.xml&quot; to &quot;META-INF\manifest.xml&quot; will move it into META-INF. But moving the file will no delete the one which has the same name in the target folder. You have to go and delete the old one. </p>
<h2><a name="changelog" id="demo3"></a>8. Changelog</h2>
<p>version 1.7.6, on 2012-06-06<br />
- Restore lost spaces around merged TBS fields in Ms Word  documents. The patch doesn't work for headers and footers, unfortunately.</p>
<p> version 1.7.5, on 2012-02-14<br />
  - Avoid erroneous Ms Word merged documents when duplicating objects such as drawings and shapes.<br />
  - Based on TbZip version 2.11<br />
  - New coding shorctut $TBS-&gt;TbsZip.<br />
  - More examples of formulas for Xlsx and Ods speadsheets.
</p>
<p>version 1.7.4, on 2011-10-20<br />
  - parameter &quot;defaut=current&quot; does not work and may build invalid  documents when the target image is missing.<br />
  - new command OPENTBS_REPLACEFILE<br />
  - new command OPENTBS_FILEEXISTS</p>
<p>version 1.7.3, on 2011-10-13<br />
  - fixed bug: in Ms Word documents, automatic fields (onload, onshow) placed in headers and footers with parameter &quot;ope=changepic&quot; are producing an erroneous merge. In Word 2010 the picture may by missing, in Word 2007 the docx file may be considered as corrupted.</p>
version 1.7.2, on 2011-10-12<br />
- fixed bug: error when using command OPENTBS_SELECT_SHEET with a sheet name: <span class="warning">Notice: Undefined index: xxx in xxx on line 1986</span>.
<p>version 1.7.1, on 2011-10-07<br />
  - fixed bug: first non-empty cell of an Excel Spreadsheet is never merged if it contains a TBS field.<br />
- minor internal improvements.</p>
<p>version 1.7.0, on 2011-08-21<br />
  - new parameter 'adjust' for changing picture size<br />
  - new command OPENTBS_DEBUG_INFO <br />
  - new command OPENTBS_SELECT_MAIN <br />
  - new command OPENTBS_SELECT_SHEET<br />
  - new command OPENTBS_DISPLAY_SHEETS<br />
  - new command OPENTBS_DELETE_SHEETS<br />
  - new command OPENTBS_DELETE_COMMENTS  <br />
  - new command OPENTBS_DELETE_ELEMENTS<br />
  - parameter 'changepic' is optimized</p>
<p>version 1.6.2, on 2011-07-12<br />
- fixed bug: Ms Excel cells could consider as error some formatted values such as  '0.00000000000000'.</p>
<p>version 1.6.1, on 2011-06-08<br />
  - fixed bug: some documents may be corrupted when created using OPENTBS_DOWNLOAD because of a PHP error <span class="warning">&quot;supplied argument is not a valid stream resource&quot;</span> or <span class="warning">&quot;Undefined property: clsOpenTBS::$OutputHandle&quot;</span>.<br />
  - fixed bug: using keyword &quot;xlsxNum&quot;, &quot;xlsxDate&quot; or &quot;xlsxBool&quot; inside a cell that is not merged can make a corrupted XLSX spreadsheet.<br />
  - improvement: updated templates in the demo.<br />
  - based on a TbsZip v2.8</p>
<p>version 1.6.0, on 2011-06-07<br />
  - new feature: merge charts in Ms Word documents.<br />
  - new feature: merge rows and columns Ms Excel workbooks.<br />
  - new feature: new &quot;ope&quot; parameters for forcing cells type in Ms Excel (Numeric, Date and Boolean).<br />
  - new feature: debug mode enhanced.<br />
  - new feature: force the type of document using command OPENTBS_FORCE_DOCTYPE.<br />
  - new property: deal with apostrophes using property OtbsConvertApostrophes.<br />
  - improvement: if the document extension is not recognized, then try to recognize document type by sub-file presence.<br />
  - improvement: can use the Direct Command feature of TBS 3.7.0.<br />
  - based on a TbsZip v2.6</p>
<p>version 1.5.0, on 2011-03-20<br />
  - new feature: headers and footers are automatically loaded for OpenOffice &amp; MsOffice.<br />
  - new feature: automatically cleans up spelling and change trackings  information in MsWord templates (such information may 
  deconstruct the TBS tags). This feature can be disabled.<br />
  - new constant OPENTBS_DEBUG_AVOIDAUTOFIELDS <br />
  - <span id="result_box4" lang="en" xml:lang="en"><span title="Cliquer ici pour voir d'autres traductions">improvement</span></span>: Debug doesn't stopped if an OpenTBS alert occurs. <br />
  - <span id="result_box3" lang="en" xml:lang="en"><span title="Cliquer ici pour voir d'autres traductions">improvement</span></span>: OpenTBS alerts say if the process will be stopped. <br />
  -    fixed bug: in debug mode: &quot;warning function.str-repeat: Second argument has to be greater than or equal to 0&quot;<br />
  - fixed bug: when using OPENTBS_RESET: &quot;Warning: Missing argument 2 for clsOpenTBS::OnCommand() in ... on line 225&quot;<br />
  - fixed bug: DML images were not found   when using parameter &quot;ope=changepic&quot; in a DOCX document<br />
  - fixed bug: the script ends and display the XML contents when a when using parameter &quot;ope=changepic&quot; with a new image type  in a DOCX document</p>
<p>version 1.4.1, on 2010-10-28<br />
  -  major bug fixed: due to TbsZip, some added or modified files can be saved the document with a wrong CRC control code. This could make  softwares to consider the document as corrupted, but were often easily   fixed by OpenOffice and Ms Office. Only few CRC codes are wrongly saved, thus the bug is rare and can seem to appear randomly on few documents.</p>
<p> version 1.4.0, on 2010-10-05<br />
  - new parameters &quot;<span class="smallcode">changepic</span>&quot; and &quot;<span class="smallcode">default</span>&quot;</p>
<p> version 1.3.3, on 2010-08-05<br />
  - property Version of OpenTBS version 1.3.2 was saying 1.3.1</p>
<p> version 1.3.2, on 2010-07-23<br />
  - possibility to change de default data conversion using the new constants <span class="smallcode">OPENTBS_DEFAULT</span>, <span class="smallcode">OPENTBS_ALREADY_XML</span> or <span class="smallcode">OPENTBS_ALREADY_UTF8</span><br />
  - enhanced debug mode: listing of added, deleted and modified files ; and show XML formated contents of files merged with OpenTBS.</p>
<p> version 1.3.1, on 2010-07-01<br />
  - based on TbsZip version 2.1: fixes a bug that saved a bad time of modification file  was added, and saved time modification when a file content is replaced.<br />
  - the addpic operator now automatically   updates the <span class="smallcode">&quot;fanifest.xml&quot;</span> file on OpenOffice document. Without this fix, an ODP merged document could be open with an error message with OpenOffice &gt;= 3.2 </p>
<p> version 1.3, on 2010-06-01<br />
  - a new plugin command that add a new file in the archive<br />
  - a new plugin command that delete a new file in the archive<br />
  - a parameter '<span class="smallcode">ope=addpic</span>' that add a new picture in the archive directly from the template<br />
  - based on a TbsZip v2 (modify/delete/add files in a zip archive, )</p>
<p>version 1.1, on 2009-11-19<br />
  - New render option : <span class="smallcode">OPENTBS_STRING</span><br />
  - New feature: can reset changes in the current archive using <span class="smallcode">$TBS-&gt;Plugin(OPENTBS_PLUGIN, OPENTBS_RESET);</span><br />
  - New behavior: extension of the archive is ignored by <span class="smallcode">LoadTemplate()</span> if the name is ended with '<span class="smallcode">#</span>'<br />
  - Bug fixed: in case of several files to take from the archive in one shot, then only the last one had [onload] fields merged.</p>
<h2><a name="license" id="demo2"></a>9. License</h2>
<p>OpenTBS is under <a href="http://www.gnu.org/licenses/lgpl.html">LGPL</a> (Lesser General Public License)</p>
<p>&nbsp;</p>
</body>
</html>
